动机 / Motivation

这个 PR 的目标，不是简单"把一个新 SDK 目录拷进主仓库"，而是把 AstrBot SDK v4 的运行时能力 以一种可以在主仓库长期维护、逐步落地、并且不破坏旧插件生态的方式接入 AstrBot。

与其说它是 SDK，不如说它是为了新旧插件都兼容的新插件扩展平台。

要解决的核心问题有 4 类：

1. 插件运行边界不清晰
   旧插件路径与主进程深度耦合，插件直接共享宿主进程内对象，插件异常、运行时污染、依赖冲突都更容易放大到整个系统。

2. 插件开发接口过于依赖宿主内部实现
   旧接口里很多能力是"直接拿宿主对象调用"的风格，虽然能用，但边界不稳定、类型约束弱、难以做清晰的能力声明，也不利于长期演进。

3. 主仓库和 SDK 仓库的职责边界需要明确
   独立的 astrbot-sdk 仓库需要作为 SDK 的 source of truth 持续演进；AstrBot 主仓库需要的是一个可消费、可同步、可测试的 vendored 运行时快照，而不是把整个 SDK 源仓库原样搬进来。

4. 迁移必须渐进，不能推翻现有插件体系
   AstrBot 现有大量逻辑仍然基于 legacy Star 插件体系。SDK 的接入必须保证：

   • 旧插件继续按旧路径工作
   • 新插件可以走 SDK 路径
   • 两者在同一条主消息流水线、Dashboard、平台命令注册体系里共存

因此，这个 PR 的真实定位是：

• 在 AstrBot 主仓库中 vendoring 一份 SDK 运行时快照
• 在主仓库中新增一层 sdk_bridge 宿主桥接层
• 让 SDK 插件能够通过协议和 capability 调用 AstrBot Core
• 同时保持 legacy 路径继续可用，形成一个 增量迁移架构

变更规模 / Change Statistics

按模块统计：

这次 PR 实际做了什么

1. 在主仓库中引入 astrbot-sdk/ 的 vendored snapshot

这个 PR 在主仓库下新增了 astrbot-sdk/ 目录，但这里必须明确：

• 这里的 astrbot-sdk/ 是 给 AstrBot 主仓库消费的 vendored subtree snapshot
• 它不是独立 astrbot-sdk 源仓库的完整镜像
• 它保留的是 AstrBot 运行时真正需要的 SDK 包布局和最小配套文件

这里保留的主要内容包括：

• src/astrbot_sdk/：SDK 运行时包主体
• pyproject.toml：让主仓库可以按本地 path dependency 使用 SDK（构建后端使用 hatchling）
• README.md / VENDORED.md / LICENSE：说明 vendoring 约定与快照边界
• templates/project_notes/AGENTS.md / CLAUDE.md：因为 astr init 仍然会生成这些模板
• testing.py、_testing_support.py、_internal/testing_support.py 等最小测试辅助：因为主仓库与模板仍然依赖这些约定

同时，很多内容是 刻意不 vendoring 进主仓库的：

• SDK 源仓库完整 docs
• 大量仅用于 SDK 仓库自身演进的测试与开发元数据

这样设计的原因是：

1. 主仓库要消费稳定快照，不是承载 SDK 全量研发现场
   AstrBot 主仓库关注的是"可运行、可集成、可回归"的 SDK 版本，而不是承接 SDK 仓库的所有开发噪音。

2. source of truth 必须单一
   SDK 行为、文档、测试体系的第一来源仍然应该是独立 astrbot-sdk 仓库。主仓库里的 astrbot-sdk/ 只是同步产物，不应该再被误解为主要开发位置。

3. 便于后续同步与审查
   scripts/sync-sdk.ps1 / scripts/sync-sdk.sh 明确要求：

   • 先更新独立 SDK 仓库
   • 再通过 subtree 同步 vendor branch 到主仓库
     这保证了变更路径清晰，减少"主仓库偷偷改 SDK vendored 文件"的维护风险。

2. 把 SDK 的运行时模型正式接入 AstrBot 主仓库

主仓库引入的不只是一个 Python package，而是一整套 SDK 运行时入口：

• protocol/：协议消息模型（messages.py、descriptors.py、_builtin_schemas.py）与描述符
• runtime/：loader / peer / transport / supervisor / worker / handler_dispatcher / capability_router / environment_groups 等运行时骨架
• clients/：17 个客户端模块，覆盖 ctx.llm、ctx.memory、ctx.db、ctx.platform、ctx.provider 等高层客户端
• decorators.py：声明式 handler/capability 注册入口（20+ 装饰器，涵盖 on_command、on_message、on_event、on_schedule、on_provider_change、validate_config、http_api、mcp_server、register_skill、background_task 等）
• context.py / events.py / message/*：插件作者直接面对的主要 API

SDK 本身的设计是比较清晰的一条链路：

插件作者 API
  -> Context / Decorators / MessageEvent
  -> 各种 typed clients
  -> CapabilityProxy / Peer
  -> Protocol messages
  -> 宿主侧 capability router

也就是说，SDK 不是让插件"直接摸宿主对象"，而是让插件通过 显式能力调用 与宿主通信。

这套设计的核心思想有三点：

1. 协议优先（protocol-first）
   先定义清楚消息模型、调用边界、错误结构，再谈功能。

2. 能力优先（capability-first）
   宿主暴露什么能力，要通过 capability 名称和 payload schema 明确表达，而不是让插件到处拿宿主内部对象直接调用。

3. 声明式优先（descriptor-first）
   handler、trigger、capability 都先变成可序列化描述符，再进入运行时分发。这让跨进程、热重载、命令面板、平台命令注册这些事情都更可控。

3. V4 协议设计

SDK 使用自定义的 v4 JSON 协议（而非 JSON-RPC）进行内部通信。这个选择经过项目成员充分讨论，定位如下：

为什么内部使用 v4 而不是 JSON-RPC：

• 把 AstrBot 的领域对象直接放进协议层（SessionRef、CapabilityDescriptor、流式能力声明、取消能力声明），不需要像 JSON-RPC 那样把运行时语义塞进 params
• 原生支持 AstrBot 的握手需求：初始化阶段交换 handlers、provided_capabilities、协议版本、元数据
• 流式调用做成明确生命周期（started/delta/completed/failed 四段式），对 LLM 输出、长任务更清晰
• 取消建模为一等协议消息 CancelMessage，不是额外约定
• 调用者身份（caller_plugin_id）和请求作用域（_request_scope_id）放进运行时链路，对权限、隔离、审计关键
• 稳定的领域错误模型（capability_not_found、protocol_version_mismatch、capability_timeout 等显式错误码）

v4 差于 JSON-RPC 的地方（已知的 trade-off）：

• 通用性差，基本是 AstrBot 私有协议
• 生态差，没有现成的客户端/调试器/跨语言支持
• batch 处理尚不如 JSON-RPC 成熟
• 协议演进成本更高

结论：v4 负责 AstrBot 内核语义，JSON-RPC 负责外部通用互联（如 MCP 接入仍然走 JSON-RPC 2.0）。

4. 插件加载与命名空间隔离

SDK 的插件加载机制使用现代 Python 隔离方案：

• _PluginScopedMetaPathFinder：注册到 sys.meta_path，拦截插件模块导入
• _plugin_scoped_import：替换 builtins.__import__，实现插件间导入隔离
• 每个插件代码被加载到 astrbot_ext_{plugin_id} 独立命名空间中
• 通过 _ensure_plugin_package() 设置模块 __path__，注册到 sys.modules

这与传统的 sys.path.insert 方式完全不同，避免了插件间的模块名冲突和全局命名空间污染。

5. 虚拟环境分组

SDK runtime 包含 environment_groups.py，实现依赖兼容性分组：

发现插件 → 按依赖兼容性分组 → 为每组创建 venv → 每个插件启动独立 Worker
   ↓            ↓                    ↓              ↓
 5个插件    用uv测试自动分组     创建2-3个venv     5个Worker进程

• 兼容的插件共享虚拟环境（节省资源）
• 冲突的插件自动分配到不同环境
• 插件更新引入新依赖冲突时，当前组环境会被重建，该插件被重新分配
• 每个插件仍然有独立的 Worker 进程（保持隔离）

6. SDK CLI 工具链

SDK 包含完整的命令行工具（astr 命令），为插件开发者提供端到端的工作流支持：

7. 插件持久化记忆系统

SDK 内置 PluginMemoryBackend（1,515 行），提供插件级别的持久化键值记忆后端：

• 存储引擎：SQLite（WAL 模式），自动管理过期条目清理
• 全文搜索：FTS5 虚拟表，支持 Unicode tokenizer
• 向量搜索：可选 FAISS 集成（IndexFlatIP + IndexIDMap2），无 FAISS 时退化为精确余弦相似度
• 混合搜索：keyword + vector 混合评分（0.65 × vector + 0.35 × keyword + 0.05 bonus）
• TTL 支持：save_with_ttl() 支持带过期时间的记忆条目
• 命名空间：层级命名空间隔离，支持 include_descendants 递归查询
• 嵌入管理：自动检测缺失嵌入、按需批量计算、脏标记驱动的增量索引构建

8. SDK 客户端面（Capability Surface）

SDK 通过 Context 暴露 17+ 类型化客户端，每个客户端背后是 capability proxy：

9. SDK 测试基础设施

SDK 提供完善的测试辅助（astrbot_sdk.testing），支持插件作者编写单元测试和集成测试：

• MockContext：完整 mock 的 Context，内置 InMemoryDB、InMemoryMemory、MockCapabilityRouter
• MockMessageEvent：可配置 user_id / group_id / platform / session 的 mock 事件
• MockLLMClient：支持预设响应（mock_response / mock_stream_response）
• MockPlatformClient：记录发送历史，支持 assert_sent 断言
• PluginHarness：从 plugin.yaml 加载插件并执行完整 dispatch 流程
• StdoutPlatformSink：将平台输出捕获到内存或 stdout

SDK 为什么这样设计

1. 为什么要做 Worker / Supervisor 运行时边界

SDK 的核心架构是把插件执行从主进程逻辑里抽出来，形成更明确的执行边界：

• Supervisor 管理 Worker 生命周期
• WorkerSession 代表一个被宿主管理的插件运行单元
• Peer + Transport 负责协议收发
• HandlerDispatcher / CapabilityDispatcher 负责把协议调用分发到真实 Python 对象

这样做的原因是：

1. 隔离故障域
   插件执行失败、卡死、局部污染时，不必直接把主进程也拖下水。

2. 隔离依赖与环境
   SDK 运行时天然更适合做环境分组、虚拟环境规划和后续多运行边界扩展。

3. 让宿主和插件关系从"对象耦合"变成"协议耦合"
   这会让系统更难写一点，但长期维护成本更低，因为边界明确以后，兼容性和演进策略才可控。

2. 为什么是 Capability Router，而不是直接暴露宿主 API

Context 下的 llm / memory / db / platform / provider / permission / kb / mcp 等客户端，本质上都是 capability 的 typed facade。

这样做的好处是：

1. 调用边界稳定
   插件只需要知道 capability 名称和参数，不需要知道宿主内部对象结构。

2. 更适合做 schema 验证与错误治理
   Capability 本身就是"一个命名的、结构化的远程调用点"，天然适合做 JSON Schema、错误码、重试语义和 docs_url。

3. 便于宿主分层实现
   主仓库里真正干活的代码仍然可以分散在 ProviderManager、PlatformManager、ConversationManager、DB、KB 等各处，但对 SDK 来说只看见统一 capability surface。

3. 为什么 handler / trigger 要走描述符，而不是靠反射硬猜

HandlerDescriptor、CommandTrigger、MessageTrigger、EventTrigger、ScheduleTrigger 这一层是 SDK 的一个重要设计点。

它解决的是：

• 插件注册了什么 handler
• 这个 handler 由什么触发
• 它属于命令、消息、系统事件还是定时任务
• 它需要什么权限、优先级、过滤器、参数模型

如果没有这一层，宿主要做的事情会很混乱：

• Dashboard 很难正确列命令
• 平台原生命令注册很难同步
• 热重载后很难稳定恢复状态
• 跨进程后宿主几乎拿不到完整元信息

描述符层的意义，本质上是把"运行时行为"先降维成"静态声明"，这样宿主侧才有机会在真正执行前做规划、注册、展示和校验。

为什么 AstrBot 主仓库还需要一层 sdk_bridge

如果 SDK 已经有 protocol、peer、capability_router，为什么主仓库还要额外实现 astrbot/core/sdk_bridge/？

因为 SDK 是通用插件运行时，AstrBot Core 则是一个已经存在多年、已有完整 legacy 体系、已有平台适配器、已有消息流水线和 Dashboard 的具体宿主。两者之间不可能无缝直接拼上，必须有一层宿主适配桥。

sdk_bridge 做的事情，本质上是把：

• AstrBot Core 的内部对象与流程
• SDK runtime 所要求的协议与能力边界

做一次明确的对接。

可以把它理解为：

• SDK 决定"插件应该怎么描述自己、怎么调用宿主、怎么收消息、怎么返回结果"
• sdk_bridge 决定"在 AstrBot 这个具体宿主里，这些事情到底接到哪里去、怎么兼容现有流水线"

sdk_bridge 的设计与职责

1. SdkPluginBridge：宿主侧总入口（2,923 行）

astrbot/core/sdk_bridge/plugin_bridge.py 是这一层的核心。

它承担了几类关键职责：

1. 插件发现与运行管理

   • 调用 SDK runtime loader 发现插件
   • 启动/维护 WorkerSession
   • 处理 reload、turn on/off、失败重试、运行状态切换

2. handler 匹配与分发

   • 收集 SDK 插件暴露出来的 handler 描述符
   • 在宿主消息到来时做 trigger matching
   • 把命中的 handler 调到对应 Worker 执行

3. 请求级状态管理

   • 通过 _RequestOverlayState 跟踪单次消息分发的 overlay 状态
   • 保存 SDK handler 返回的 sent_message / stop / call_llm
   • 管理 SDK-local extras、effective result、handler whitelist 等请求级数据

4. 宿主侧面板与管理接口

   • 给 Dashboard 提供命令、工具、插件元信息、配置 schema
   • 给平台适配器提供 native command candidates
   • 接 SDK HTTP API 路由分发

5. 宿主事件桥接

   • 分发 message event
   • 分发 system event，比如 decorating_result、agent_begin、agent_done 等
   • 处理 event/result payload 与宿主消息模型之间的转换

2. CoreCapabilityBridge：把 AstrBot Core 能力整理成 SDK capability surface

astrbot/core/sdk_bridge/capability_bridge.py 是一个 70 行的组合类，通过多重继承从 13 个 Mixin 类组合所有能力。

当前拆分出的能力组包括（对应 sdk_bridge/capabilities/ 下的 mixin 文件）：

3. 其他桥接组件

4. _RequestOverlayState：请求覆盖层

这是 bridge 设计里最容易被忽略、但实际上非常关键的部分。

AstrBot 原有流水线不是为"SDK 插件在另一套 runtime 里执行，并返回 stop/call_llm/result 覆盖行为"而设计的。为了在不重写整个流水线的前提下把 SDK 接进去，必须引入一层 请求级 overlay state。

它解决的核心问题是：

1. SDK handler 返回的结果要能影响宿主后续流水线
2. 这些影响必须是"本次请求级"的，而不是全局状态
3. 宿主现有 stage 必须能读取"effective result"而不是只读 event.get_result()

这是一个很典型的增量架构设计：不硬推翻旧流水线，不把 SDK 行为偷偷塞进全局变量，而是在请求粒度建立一个明确的覆盖层。

这个 bridge 是如何嵌入 AstrBot 现有生命周期的

1. Core Lifecycle 接入

astrbot/core/core_lifecycle.py 里，这个 PR 增加了：

• 初始化 SdkPluginBridge（from astrbot.core.sdk_bridge import SdkPluginBridge）
• 把 bridge 注入 star_context
• 在核心启动阶段 start() 它

2. Pipeline 接入

改动点主要在 pipeline 各 stage，核心改动是让 pipeline 在关键节点具备以下能力：

1. 在 legacy handlers 执行后，继续调度 SDK handlers
2. 如果 SDK handler 已经发送消息或终止传播，宿主要知道
3. 如果 SDK handler 改写了 result，后续 stage 应该读取 effective result
4. call_llm 的最终决策不能再只看 legacy event 状态，还要看 SDK overlay 决策
5. decorating_result 这类宿主事件也需要反向派发给 SDK

设计重点是 共存而非替换——legacy handler 路径继续跑，SDK 路径在合适阶段接入，最终结果由 bridge 的请求级状态协调。

3. Dashboard 接入

Dashboard 相关改动遵循以下设计策略：

1. SDK 命令标记为只读（source of truth 在插件描述符）
2. SDK tools 纳入统一工具面板，支持激活/停用
3. 配置 schema 通过 bridge 获取，不复制配置逻辑

4. 平台原生命令接入

在 Telegram / Discord 适配器里，增加了从 bridge 读取 native command candidates 的逻辑。同一份元数据既能驱动运行时触发，也能驱动 Dashboard 展示，还能驱动平台命令注册。

5. 新增 weixin_oc 平台适配器

新增企业微信（WeCom Open Platform）适配器，包含 adapter、client、event 三个模块。

测试覆盖

本 PR 新增大量测试代码，分布在以下区域：

兼容性与迁移结论

Breaking Changes

• 这个 PR 不以破坏 legacy Star 插件兼容性为目标

预期兼容策略是：

• legacy Star 插件继续走现有宿主逻辑
• SDK 插件走新的 runtime + bridge 逻辑
• 两者共用同一个 AstrBot Core 生命周期与主消息流水线

这是一个 宿主能力扩展与架构铺路，而不是激进替换。新架构代码全部放在 _internal 包内，不会与现有架构产生冲突。

从迁移角度看，它建立的是一个可逐步迁移的双轨体系：

• 老插件不必立刻重写
• 新插件可以开始按 SDK v4 的方式开发
• 宿主逐步把新能力纳入 capability surface

已知待解决事项

• 批量请求：v4 协议的批量处理能力尚未完善(但是使用前景不高)

验证方式 / Verification

# AstrBot 主仓库侧 SDK 集成与兼容性测试
uv run pytest tests/test_sdk/ -q
uv run pytest tests/test_dashboard.py tests/test_db_backward_compat.py tests/test_computer_config.py -q
uv run pytest tests/test_plugin_manager.py tests/test_platform_register.py -q

# 可选：独立 astrbot-sdk 源仓库侧回归
cd ../astrbot-sdk
uv run pytest tests/test_runtime_peer.py tests/test_mcp_runtime.py tests/test_sync_vendor_script.py -q

Checklist / 检查清单

• 已明确 astrbot-sdk/ 在主仓库中是 vendored snapshot，而不是完整 SDK 源仓库
• 已解释 SDK 采用 protocol-first / capability-first / descriptor-first 的设计原因
• 已解释 sdk_bridge 在 AstrBot 宿主中的职责、边界和存在必要性
• 已说明当前集成策略是与 legacy Star 共存，而不是直接替换旧体系
• 已补充变更规模统计（260 文件、73,102 行新增、510 commits）
• 已补充 SDK CLI 工具链说明（init/validate/build/dev/run/serve-worker/worker）
• 已补充插件持久化记忆系统说明（SQLite + FTS5 + FAISS）
• 已补充 SDK 客户端面详细列表（17+ 类型化客户端）
• 已补充测试覆盖范围说明（26+ 单元测试文件）
• 已补充 v4 协议设计理由（为什么不用 JSON-RPC）
• 已补充插件加载隔离机制（MetaPathFinder + astrbot_ext_ 命名空间）
• 已补充虚拟环境分组机制（environment_groups）
• 已补充新平台适配器（weixin_oc）
• 已补充构建系统（hatchling）
• 已修正 plugin_bridge.py 行数为实际 2,923 行
• 已补充 sdk_bridge 完整文件列表（含 dispatch_engine、lifecycle_manager、mcp_manager 等）
• 已标注已知待解决事项（MD5 安全审查、批量请求）